List Files

GET/api/v1/users/me/files

Lists the authenticated patient's case attachments. Optionally filtered by case and PHI/general type. Soft-deleted rows are excluded. Sorted by createdAt descending.

Bearer accessToken

Productionhttps://api.care360-next.carevalidate.com/api/v1/users/me/files

Staginghttps://api-staging.care360-next.carevalidate.com/api/v1/users/me/files

Headers

Headers

Authorizationstringrequired

Bearer access token from /verify-otp.

Example: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...

Query Parameters

Query Parameters

caseIdstringoptional

UUID. Restrict the list to a single case owned by the patient. Verified via ensurePatientOwnsCase — if the case does not belong to the patient or to the calling org, returns 403.

Example: 550e8400-e29b-41d4-a716-446655440000

typestringoptional

Filter by isPHI. Omit to include both.

Values:phigeneral

limitnumberoptional

Maximum number of files to return. Must be a positive integer between 1 and 100 (inclusive). Defaults to 50 when omitted. The response does not include a pagination cursor; use `caseId` or `type` to narrow results when your patient has more than 100 attachments.

Example: 25

Behavior

1. If caseId is provided, ensurePatientOwnsCase confirms the case exists, the submitterId === userId, and the organizationId matches the calling org. Otherwise → 403 VALIDATION_ERROR "You do not have access to this case".
2. If caseId is omitted, the server resolves the patient's own case ids in this org.
3. The DB query lists CaseAttachment rows for those case ids with isDeleted: false, optionally filtered by isPHI, ordered by createdAt descending.
4. Results are capped at limit rows (default 50, max 100). No pagination cursor is returned; call again with a narrower caseId or type filter if you need to surface more files.
5. A signed viewUrl is minted per file. If the underlying GCS object is missing for an orphaned DB record, viewUrl and viewUrlExpiresIn are null for that file only — the rest of the list is unaffected. Other storage errors (e.g. a temporary outage) return an error response for the whole request instead of null.

If the patient has no cases (or the case has no attachments), data.files is [].

Response Shape

Each list item — see Files Overview › Attachment Object Shapes.

Example Request

cURL — all

curl -X GET '<BASE_URL>/api/v1/users/me/files' \
-H 'Authorization: Bearer <accessToken>'

cURL — filtered

curl -X GET '<BASE_URL>/api/v1/users/me/files?caseId=<CASE_ID>&type=general' \
-H 'Authorization: Bearer <accessToken>'

JavaScript

const url = new URL('<BASE_URL>/api/v1/users/me/files');
url.searchParams.set('caseId', '<CASE_ID>');
url.searchParams.set('type', 'general');

const response = await fetch(url, {
method: 'GET',
headers: {
  'Authorization': 'Bearer <accessToken>',
},
});
const data = await response.json();
console.log(data);

Python

import requests

response = requests.get(
  '<BASE_URL>/api/v1/users/me/files',
  headers={
      'Authorization': 'Bearer <accessToken>',
  },
  params={'caseId': '<CASE_ID>', 'type': 'general'},
)
print(response.json())

Responses

▶200SuccessReturns the patient-visible attachments matching the filters.

{
  "status": 200,
  "success": true,
  "data": {
    "files": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "fileName": "lab-result.pdf",
        "isPHI": true,
        "isRestricted": false,
        "caseId": "550e8400-e29b-41d4-a716-446655440111",
        "uploadedBy": {
          "id": "550e8400-e29b-41d4-a716-446655440222",
          "firstName": "Jane",
          "lastName": "Doe"
        },
        "createdAt": "2026-04-15T12:34:56.000Z",
        "viewUrl": "https://storage.googleapis.com/...?GoogleAccessId=<serviceAccount>&Expires=<unixTimestamp>&Signature=<sig>&response-content-disposition=inline",
        "viewUrlExpiresIn": 3600
      }
    ]
  }
}

▶400Validation errorcaseId is not a UUID, or type is not phi/general.

{
  "status": 400,
  "success": false,
  "error": "Validation failed",
  "code": "VALIDATION_ERROR"
}

▶401Authentication failureAuth-middleware rejection (any cause is collapsed into this generic response).

{
  "status": 401,
  "success": false,
  "error": "Invalid or expired token",
  "code": "VALIDATION_ERROR"
}

▶403Case not ownedcaseId does not belong to the patient or to the calling org.

{
  "status": 403,
  "success": false,
  "error": "You do not have access to this case",
  "code": "VALIDATION_ERROR"
}

▶429Rate limit exceededMore than 30 requests per minute from this organization on this endpoint.

{
  "status": 429,
  "success": false,
  "error": "Rate limit exceeded",
  "message": "Maximum 30 requests per 60 seconds exceeded",
  "retryAfter": 60,
  "code": "CASE_ERROR"
}

Try It Out

Try itAPI Playground

▶